Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Few changes to 05-snapshots... to complete the instructions. #941

Closed
wants to merge 1 commit into from
Closed

Few changes to 05-snapshots... to complete the instructions. #941

wants to merge 1 commit into from

Conversation

why-not-try-calmer
Copy link
Contributor

Fixed very small gaps in the instructions.

@Minoru
Copy link
Collaborator

Minoru commented Jun 16, 2022

I think the tutorial is short and simple enough that the reader doesn't need all the code repeated at the end. Thanks for the work, sorry I won't merge this!

@Minoru Minoru closed this Jun 16, 2022
@why-not-try-calmer
Copy link
Contributor Author

why-not-try-calmer commented Jun 16, 2022 •
edited
Loading

I think the tutorial is short and simple enough that the reader doesn't need all the code repeated at the end. Thanks for the work, sorry I won't merge this!

Thanks, I think you didn't get an important point, which is that the tutorial is incomplete: following the tutorial will not get the user to build the target .xml file. This is a severe shortcoming which, I think you'll admit, deserves to be addressed, which is what this PR does.

I am given to understand that you find the fixed tutorial too long. It's however quite trivial to fix. See #942.

@why-not-try-calmer why-not-try-calmer mentioned this pull request Jun 16, 2022
Open
@Minoru
Copy link
Collaborator

Minoru commented Jun 16, 2022 •
edited
Loading

I followed the tutorial and got the .xml file:

$ mkdir demo
$ cd demo
$ hakyll-init .

# I picked this snapshot to save time, as I already have Hakyll built from it
$ stack init --resolver=lts-19.0

$ cat > site.hs
{-# LANGUAGE OverloadedStrings #-}
import           Data.Monoid (mappend)
import           Hakyll

myFeedConfiguration :: FeedConfiguration
myFeedConfiguration = FeedConfiguration
    { feedTitle       = "Healthy cooking: latest recipes"
    , feedDescription = "This feed provides fresh recipes for fresh food!"
    , feedAuthorName  = "John Doe"
    , feedAuthorEmail = "[email protected]"
    , feedRoot        = "http://healthycooking.example.com"
    }

main :: IO ()
main = hakyll $ do
    match "templates/*" $ compile templateBodyCompiler

    create ["atom.xml"] $ do
        route idRoute
        compile $ do
            let feedCtx = postCtx `mappend`
                    constField "description" "This is the post description"

            posts <- fmap (take 10) . recentFirst =<< loadAll "posts/*"
            renderAtom myFeedConfiguration feedCtx posts

    match "posts/*" $ do
        route $ setExtension "html"
        compile $ pandocCompiler
            >>= loadAndApplyTemplate "templates/post.html"    postCtx
            >>= saveSnapshot "content" -- new
            >>= loadAndApplyTemplate "templates/default.html" postCtx
            >>= relativizeUrls

postCtx :: Context String
postCtx =
    dateField "date" "%B %e, %Y" `mappend`
    defaultContext

$ stack run -- rebuild
Building all executables for `demo' once. After a successful build of all of them, only specified executables will be rebuilt.
demo> configure (exe)
Configuring demo-0.1.0.0...
demo> build (exe)
Preprocessing executable 'site' for demo-0.1.0.0..
Building executable 'site' for demo-0.1.0.0..
[1 of 1] Compiling Main
Linking .stack-work/dist/x86_64-linux-tinfo6/Cabal-3.4.1.0/build/site/site ...
demo> copy/register
Installing executable site in /dev/shm/demo/.stack-work/install/x86_64-linux-tinfo6/864ae7271f046b5e971924514cb85ad8fda36e70b25dbc7c638bccac862df299/9.0.2/bin
Removing _site...
Removing _cache...
Removing _cache/tmp...
Initialising...
  Creating store...
  Creating provider...
  Running rules...
Checking for out-of-date items
Compiling
  updated templates/archive.html
  updated templates/post-list.html
  updated templates/default.html
  updated templates/post.html
  updated posts/2015-08-12-spqr.markdown
  updated posts/2015-11-28-carpe-diem.markdown
  updated posts/2015-10-07-rosa-rosa-rosam.markdown
  updated posts/2015-12-07-tu-quoque.markdown
  updated atom.xml
Success

Am I missing something here?

@why-not-try-calmer
Copy link
Contributor Author

why-not-try-calmer commented Jun 16, 2022 •
edited
Loading

Am I missing something here?

Yup. Or better said: you're are adding an extra bit which is absent from the tutorial (I am referring to its web rendering): a call site for the (body of) the unamed function:

create ["atom.xml"] $ do
    route idRoute
    compile $ do
        let feedCtx = postCtx `mappend` bodyField "description"
        posts <- fmap (take 10) . recentFirst =<<
            loadAllSnapshots "posts/*" "content"
        renderAtom myFeedConfiguration feedCtx posts

Adding stuff that's not explicit in tutorials happens when you know what you're doing. But I think it's a nice move to new users to offer them explicitness when possible -- especially users who might not be very comfortable with Haskell.

The PR is now closed, but see #942.

@Minoru
Copy link
Collaborator

Minoru commented Jun 17, 2022

Calling create is explained in part three of the tutorial. Sorry, I don't think the problem you're trying to fix here exists, so please close #942 — I won't merge it either.

@why-not-try-calmer
Copy link
Contributor Author

why-not-try-calmer commented Jun 17, 2022 •
edited
Loading

Calling create is explained in part three of the tutorial. Sorry, I don't think the problem you're trying to fix here exists, so please close #942 — I won't merge it either.

Can you show me exactly where you see the tutorial tell the user about the call site for create?

Of course, here we are talking about https://jaspervdj.be/hakyll/tutorials/05-snapshots-feeds.html. If what you have in mind is https://jaspervdj.be/hakyll/tutorials/03-rules-routes-compilers.html, featuring indeed the sentence:

However, we can see that one item makes no use of match, but uses create instead.

that's a completely different tutorial, and it would be more user friendly to not assume that they have read it before reading the tutorial about snapshots (unless there is a mention somewhere that tutorials should be read in order).

@Minoru
Copy link
Collaborator

Minoru commented Jun 17, 2022

Yes, I had the third part in mind. The fact that they should be read in order can be derived from how they're titled on the "Tutorials" page: "Tutorial series".

@why-not-try-calmer
Copy link
Contributor Author

why-not-try-calmer commented Jun 17, 2022 •
edited
Loading

@jaspervdj Sorry to ping you but I'd like to hear your opinion on this. To me all this sounds like making things unnecessarily complicated for new users, which may or may not be familiar with Haskell, and may be at various degree. I do not understand why making things explicit is worse than making them implicit.

I also take note of the fact that https://jaspervdj.be/hakyll/tutorials/03-rules-routes-compilers.html does not really address the problem, as it does not make it explicit the call site for create.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@why-not-try-calmer @Minoru